Welcome to EOELAB!

EOELAB 运维手册

EOELAB 运维手册

本文档面向运维人员，说明如何操作本地域、数据设施、网络设施以及加入联邦。

阅读导览

本地域节点初始化

基础配置

  1. 安装 Debian stable + Incus stable（https://github.com/zabbly/incus）
  2. 根文件系统使用 Btrfs，并配置 raid1/10
  3. 主机名使用 DomainPrefix-Number 格式，例如 core0-1
  4. 禁用 swap：
    • 安装系统时不创建 swap 分区，或
    • 执行 swapoff -a 并永久移除 /etc/fstab 中的 swap 条目
  5. 仅使用 SSH 密钥登录，关闭密码验证
  6. 确认时间通过 systemd-timesyncd 同步 UTC，无需额外配置 NTP

大页内存配置

静态大页

  1. 关闭 THP（参考 https://anotherboringtechblog.com/2024/02/disabling-thp-ubuntu-22-04/）
  2. 添加 /etc/sysctl.d/hugepages.conf，内容为：
    vm.nr_hugepages = SIZE
    其中 SIZE = HP_Capacity / 2MiB

注意：当前 Incus 的内存占用统计只统计 4k 大小的普通页，因此实例使用大页内存时，要额外关注 hugetlb 余量。

THP

Debian 默认开启 THP。对于 JVM，额外添加 -XX:+UseTransparentHugePages 标志显式激活。

计算设施操作

生成 TLS 客户端证书

openssl req -newkey rsa:2048 -nodes -keyout client.key -x509 -days 3650 -out client.crt -subj "/CN=Common Name"

在本地域节点添加信任证书：

incus config trust add-certificate client.crt

导出 pfx 证书供浏览器使用：

openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt

CLI 连接：

mv client.key client.crt ~/.config/incus/
incus remote add ALIAS IP/NS --accept-certificate

OIDC 接入

OIDC 鉴权通过添加联邦认证设施（Zitadel）实现。具体配置参考认证设施 endpoint：https://authn.eoelab.org

实例访问

  1. 通过 WebUI 的 terminal / console 操作实例
  2. 文件上传/下载：
    1. 通过 proxy 设备配置 SSH 端口
    2. 通过 terminal 添加公钥
    3. 启动 SSH 服务：
      • Debian 系：service ssh start
      • Alpine 系：/usr/sbin/sshd
    4. 使用 ssh/scp 上传/下载文件

嵌套 OCI 容器

默认不允许在 LXC 中嵌套运行 OCI 容器。容器部署服务可直接以 OCI 实例运行在 Incus 上，并使用 Incus 网络内部通信。例外：CI/CD 中使用 Kaniko 构建 OCI 镜像。

数据设施操作

存储接口命名

按照 <接口类型>_<介质><容量><性能> 格式命名。

例如 fs_nml：文件系统接口 / NVMe / 1–4T / 性能 l。

选择存储策略

  1. 热数据：强制多副本
  2. 温/冷数据：
    • TrueNAS：RAID-Z，优先 Z2
    • Ceph：EC，温数据 4+2，冷数据 8+3 或更高
  3. 磁盘极少（每节点 1–2 盘）时使用多副本，避免 EC 小文件放大

部署 Btrfs 本地存储

Btrfs 接口为 fs，由节点本地提供。

部署 TrueNAS 共享存储

  1. TrueNAS 接口为 bs，由 TrueNAS 远程提供
  2. TrueNAS 节点命名为 nas
  3. 适用规模：3–6 节点

部署 Ceph 共享存储

  1. 适用规模：≥7 节点
  2. 命名：与计算设施同名（超融合）或 ceph-Number（独立集群）
  3. Ceph 集群网络使用独立 IP 子网，接入网口配置同网段静态 IP 且不设网关
  4. 存储接口选择：
    • fs：多节点读写，适合对 I/O 延迟不敏感的文件读写
    • bs：读写延迟双低，适合数据库
    • os：大数据或海量小文件

网络设施操作

物理网络架设

根据带宽选择方案：

带宽方案
1/2.5G电口（RJ45 + CAT6），无 RDMA
10G光口（SFP+ + DAC）+ RoCEv2
≥40G光口（QSFP+ + DAC）+ 强制 RoCEv2

注意：使用 RoCEv2 需要支持 PFC 和 ECN 的网卡与交换机；光口默认使用 DAC 线，无需光模块。

公网接入

  1. 使用硬件路由器/防火墙作为本地域网关
  2. 一个本地域只绑定一个子域名证书作为公网出口
  3. NAT 型：本地域入口解析到网关，通过端口转发/DMZ 主机转发到节点
  4. 互通型：本地域入口直接解析到节点

虚拟网络配置

  1. 单节点使用 bridge，集群使用 ovn,整个本地域有且仅有一个虚拟网络
  2. 用户态接口命名：INTERFACE-Domain
  3. 地址池默认使用 172.16.0.0/12
  4. 实例默认接入设备 eth0；VM 需要 proxy 设备时可设置静态地址：
    eth0:
    ipv4.address: 实例静态ip
    network: 接入网络
    type: nic
  5. 实例使用 proxy 设备暴露服务：
    • 容器（lxc/oci）：Listen 为外部端口，connect 为内部端口
    • vm：NAT mode 启用，Listen 的 IP 为节点 IP，connect 的 IP 为实例静态 IP

ACL 配置示例

  1. block-host：丢弃主机地址段流量：

    • Drop Any 10.0.0.0/8
    • Drop Any 192.168.0.0/16

  2. block-internal：丢弃内部地址段流量：

    • Drop Any 172.16.0.0/12

加入联邦

如何获得用户账户

  1. 访问 https://authn.eoelab.org 自主注册，或基于 GitHub 创建账户
    • 此时不会得到任何权限
    • 基于外部 IDP 创建账户后，由于空密码将无法自主重置密码，必须联系 admin 团队设置初始密码
  2. 向 admin 团队邮件/协作设施发送自我介绍，说明身份、技术背景或使用目的
  3. admin 团队审核通过后，Zitadel 账户将被赋予基本用户权限（core 项目角色权限）

申请人需满足以下任一条件：

获得用户权限后，才可以将设备加入联邦。

退出与清理

EOELAB 不支持静默退出。需要退出时向 admin 团队发送退出邮件，admin 团队将执行：

对于本地域，还包括：

长期失联或存在安全风险的节点可能被强制移除。

独立的Openfga实例

  1. 数据库命名为Domain_openfga
  2. 内部容器命名为Domain-openfga
  3. 尾部端点命名为Domain

客户端加入联邦网络

  1. 下载客户端：https://tailscale.com/download
  2. 执行：
    sudo tailscale up --login-server https://hs.eoelab.org
  3. 更多细节参考：https://headscale.net/stable/usage/getting-started/

注意：在云服务器上激活客户端可能导致内部镜像解析到 CGNAT 范围，可换源到公网站点（如 USTC 镜像源）。

部署 DERP 中继节点

  1. 下载客户端并登录：
    tailscale login --login-server https://hs.eoelab.org
  2. 使用以下 Docker Compose 部署 DERP（放行 3478/12345 端口）：
    services:
  derper:
    image: ghcr.io/yangchuansheng/derper:v1.98.8
    ports:
      - 3478:3478/udp
      - 12345:12345
    environment:
      DERP_DOMAIN: example.com
      DERP_CERT_DIR: /cert
      DERP_ADDR: ':12345'
      DERP_STUN_PORT: '3478'
      DERP_HTTP_PORT: '-1'
      DERP_VERIFY_CLIENTS: "true"
    volumes:
      - ./cert:/cert
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
  3. 向 https://codeberg.org/eoelab/Derpmap 提交 PR 增加节点，注意：
    • 区域代码为 chn（ISO 3166-1 三字母规范），区域名称使用国家全称
    • 中国大陆（chn, ID 为 900）只接收来自中国大陆的中继节点，港澳台除外
    • 建议 DERP 启用客户端验证避免滥用

注意：不接受自签名节点，必须包含公共 CA 证书；中国大陆云服务器必须使用备案域名作为入口点。

原生设施使用

申请联邦域名与证书

具备公网的本地域/服务设备默认可获得 eoelab.org 子域名。节点本地生成并保存私钥，联邦设施基于 DNS-01 challenge 完成 ACME 验证与证书签发。节点通过唯一身份凭证获取自身被授权域名的证书。

申请自托管 Runner

  1. 在 Codeberg Actions 页面创建新的 runner
  2. 将以下内容发送给 admin 团队：
    connections:
  forgejo:
    url: https://codeberg.org/
    uuid: UUID
    token: TOKEN
    • 实际注册时 forgejo 将替换为申请人的用户名，用于内部区分、避免同名 key 冲突

通用 runner tag

维度取值
sizetiny（2–4G）、small（4–8G）、medium（8–16G）
archamd64、riscv64
runtimelxc（标准）、vm（全功能）

专用 runner tag

使用监控设施

用途endpoint框架
数据源VictoriaMetrics
可视化Grafana
日志VictoriaLogs
告警Alertmanager

部署检查清单

本地域节点

数据设施

网络设施

加入联邦

Post list